<!DOCTYPE HTML>
<html lang="en">
<head>
<title>KeyWait - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The KeyWait command waits for a key or mouse/joystick button to be released or pressed down." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>KeyWait</h1>

<p>Waits for a key or mouse/joystick button to be released or pressed down.</p>

<pre class="Syntax"><span class="func">KeyWait</span>, KeyName <span class="optional">, Options</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>KeyName</dt>
  <dd><p>This can be just about any single character from the keyboard or one of the key names from the <a href="../KeyList.htm">key list</a>, such as a mouse/joystick button. Joystick attributes other than buttons are not supported.</p>
      <p>An explicit virtual key code such as <code>vkFF</code> may also be specified. This is useful in the rare case where a key has no name and produces no visible character when pressed. Its virtual key code can be determined by following the steps at the bottom fo the <a href="../KeyList.htm#SpecialKeys">key list page</a>.</p></dd>

  <dt>Options</dt>
  <dd><p>If this parameter is blank, the command will wait indefinitely for the specified key or mouse/joystick button to be physically released by the user. However, if the <a href="_InstallKeybdHook.htm">keyboard hook</a> is not installed and <em>KeyName</em> is a keyboard key released artificially by means such as the <a href="Send.htm">Send</a> command, the key will be seen as having been physically released. The same is true for mouse buttons when the <a href="_InstallMouseHook.htm">mouse hook</a> is not installed.</p>
      <p>Options: A string of one or more of the following letters (in any order, with optional spaces in between):</p>
      <p><strong>D</strong>: Wait for the key to be pushed down.</p>            
      <p><strong>L</strong>: Check the logical state of the key, which is the state that the OS and the active window believe the key to be in (not necessarily the same as the physical state). This option is ignored for joystick buttons.</p>
      <p><strong>T</strong>: Timeout (e.g. <code>T3</code>). The number of seconds to wait before timing out and setting <a href="../misc/ErrorLevel.htm">ErrorLevel</a> to 1. If the key or button achieves the specified state, the command will not wait for the timeout to expire. Instead, it will immediately set <a href="../misc/ErrorLevel.htm">ErrorLevel</a> to 0 and the script will continue executing.</p>
      <p>The timeout value can be a floating point number such as 2.5, but it should not be a hexadecimal value such as 0x03.</p></dd>

</dl>

<h2>ErrorLevel</h2>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if the command timed out or 0 otherwise.</p>
<h2>Remarks</h2>
<p>The physical state of a key or mouse button will usually be the same as the logical state unless the keyboard and/or mouse hooks are installed, in which case it will accurately reflect whether or not the user is physically holding down the key. You can determine if your script is using the hooks via the <a href="KeyHistory.htm">KeyHistory</a> command or menu item. You can force either or both of the hooks to be installed by adding the <a href="_InstallKeybdHook.htm">#InstallKeybdHook</a> and <a href="_InstallMouseHook.htm">#InstallMouseHook</a> directives to the script.</p>
<p>While the command is in a waiting state, new <a href="../misc/Threads.htm">threads</a> can be launched via <a href="../Hotkeys.htm">hotkey</a>, <a href="Menu.htm">custom menu item</a>, or <a href="SetTimer.htm">timer</a>.</p>
<p>To wait for two or more keys to be released, use KeyWait consecutively. For example:</p>
<pre>KeyWait Control  <em>; Wait for both Control and Alt to be released.</em>
KeyWait Alt</pre>
<p>To wait for any one key among a set of keys to be pressed down, see the examples section of the <a href="Input.htm">Input</a> command.</p>
<h2>Related</h2>
<p><a href="GetKeyState.htm">GetKeyState</a>, <a href="../KeyList.htm">Key List</a>, <a href="Input.htm">Input</a>, <a href="KeyHistory.htm">KeyHistory</a>, <a href="_InstallKeybdHook.htm">#InstallKeybdHook</a>, <a href="_InstallMouseHook.htm">#InstallMouseHook</a>, <a href="ClipWait.htm">ClipWait</a>, <a href="WinWait.htm">WinWait</a></p>
<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: Basic usage</p>
<pre>KeyWait, a  <em>; Wait for the A key to be released.</em>
KeyWait, LButton, D  <em>; Wait for the left mouse button to be pressed down.</em>
KeyWait, Joy1, D T3  <em>; Wait up to 3 seconds for the first joystick button to be pressed down.</em>
KeyWait, LAlt, L  <em>; Wait for the left Alt key to be logically released.</em></pre>
</div>

<div class="ex" id="ExHotkey">
<p><a href="#ExHotkey">#2</a>: A simple hotkey</p>
<pre>~CapsLock::
KeyWait, CapsLock  <em>; Wait for user to physically release it.</em>
MsgBox You pressed and released the CapsLock key.
return</pre>
</div>

<div class="ex" id="ExRemap">
<p><a href="#ExRemap">#3</a>: Remapping a key or mouse button (this is only for illustration because it would be easier to use the <a href="../misc/Remap.htm">built-in remapping feature</a>). The left mouse button is kept held down while NumpadAdd is down, which effectively transforms NumpadAdd into the left mouse button.</p>
<pre>*NumpadAdd::
MouseClick, left,,, 1, 0, D  <em>; Hold down the left mouse button.</em>
KeyWait, NumpadAdd  <em>; Wait for the key to be released.</em>
MouseClick, left,,, 1, 0, U  <em>; Release the mouse button.</em>
return</pre>
</div>

<div class="ex" id="ExDouble">
<p><a href="#ExDouble">#4</a>: Detects when a key has been double-pressed (similar to double-click). KeyWait is used to stop the keyboard's auto-repeat feature from creating an unwanted double-press when you hold down the RControl key to modify another key. It does this by keeping the hotkey's thread running, which blocks the auto-repeats by relying upon #MaxThreadsPerHotkey being at its default setting of 1. Note: There is a more elaborate script to distinguish between single, double, and triple-presses at the bottom of the <a href="SetTimer.htm">SetTimer</a> page.</p>
<pre>~RControl::
if (A_PriorHotkey != &quot;~RControl&quot; or A_TimeSincePriorHotkey &gt; 400)
{
    <em>; Too much time between presses, so this isn't a double-press.</em>
    KeyWait, RControl
    return
}
MsgBox You double-pressed the right control key.
return</pre>
</div>

</body>
</html>
